package org.as3search.providers {
	/*
	 * as3search - http://code.google.com/p/as3search
	 * Copyright (c) 2009-2010 by respective authors. All rights reserved.
	 *
	 * This library is free software; you can redistribute it and/or modify it under the
	 * terms of the GNU Lesser General Public License as published by the Free Software
	 * Foundation; either version 2.1 of the License, or (at your option) any later
	 * version.
	 *
	 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
	 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
	 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
	 *
	 * You should have received a copy of the GNU Lesser General Public License along
	 * with this library; if not, write to the Free Software Foundation, Inc.,
	 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	 */
	
	/**
	 * <code>SearchProvider</code> is a type that "wraps" 
	 * collection types to provide a unified interface through
	 * which to iterate collections. as3search provides several 
	 * <code>SearchProvider</code> implementations by default,
	 * namely <code>ArraySearchProvider</code>, <code>FlexListSearchProvider</code>,
	 * and <code>ObjectSearchProvider</code>. If you are familiar with
	 * Java <code>Iterator</code> types, <code>SearchProvider</code>
	 * should seem very familiar to you. <br/><br/>
	 * 
	 * @see org.as3search.providers.ArraySearchProvider
	 * @see org.as3search.providers.FlexListSearchProvider
	 * @see org.as3search.providers.ObjectSearchProvider
	 */
	public interface SearchProvider {
		/**
		 * Whether or not this iterator has another item in it.
		 * @example Calls to <code>next()</code> move the cursor position
		 * forward, allowing for easy while-looping over the collection.
		 * <listing version="3.0">
		 * while (provider.hasNext()) {
		 * 	var value:Object = provider.next();
		 * }
		 * </listing>
		 * @return	Returns true if there is another item left in the collection,
		 * 		false otherwise.
		 */
		function hasNext():Boolean;
		/**
		 * Retrieves the next item in the collection and moves the cursor forward.
		 * @return	Returns the next object in the collection.
		 */
		function next():Object;
		/**
		 * Resets the cursor position to 0 to allow looping over the collection multiple
		 * times.
		 * @example After looping through the collection, <code>reset()</code> allows you to
		 * start over and loop through again.
		 * <listing version="3.0">
		 * while (provider.hasNext()) {
		 * 	var value:Object = provider.next();
		 * }
		 * 
		 * provider.reset();
		 * 
		 * while (provider.hasNext()) {
		 * 	...
		 * }
		 * </listing>
		 */
		function reset():void;
		/**
		 * The colllection object which this <code>SearchProvider</code> wraps. 
		 */
		function get target():Object;
		function set target(value:Object):void;
		/**
		 * The size of the collection.
		 */
		function get length():Number;
	}
}